﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<title>Email Sending</title>
<link type="text/css" rel="stylesheet" href="bootstrap.min.css" />
</head>

<body>

<div class="document-contents">

<h3>Introduction</h3>
<p>Email sending is a pretty common task for almost every application. ASP.NET 
Boilerplate provides a basic infrastructure to simply send emails and seperate 
email server configuration from sending emails.</p>
	<h3>IEmailSender</h3>
	<p><strong>IEmailSender</strong> is a service to simply send emails without knowing details. 
	Example usage:</p>
	<pre lang="cs">public class TaskManager : IDomainService
{
    <strong>private readonly IEmailSender _emailSender;
</strong>
    public TaskManager(<strong>IEmailSender emailSender</strong>)
    {
        _emailSender = emailSender;
    }

    public void Assign(Task task, Person person)
    {
        //Assign task to the person
        task.AssignedTo = person;

        //Send a notification email
<strong>        _emailSender.Send(
            to: person.EmailAddress,
            subject: "You have a new task!",
            body: $"A new task is assigned for you: &lt;b&gt;{task.Title}&lt;/b&gt;",
            isBodyHtml: true
        );</strong>
    }
}</pre>
	<p>We simply <a href="Dependency-Injection.html">injected</a> <strong>
	IEmailSender </strong>and used <strong>Send </strong>method. Send method has 
	a few more overloads. It can also get a MailMessage object (not available 
	for .net core since .net core does not include SmtpClient and MailMessage).</p>
	<h4>ISmtpEmailSender</h4>
	<p>There is also <strong>ISmtpEmailSender</strong> which extends 
	IEmailSender and adds <strong>BuildClient</strong> method to create an
	<strong>SmtpClient</strong> to directly use it (not available for .net core 
	since .net core does not include SmtpClient and MailMessage). Using 
	IEmailSender will be enough for most cases.</p>
	<h4>NullEmailSender</h4>
	<p>There is also a
	<a href="https://en.wikipedia.org/wiki/Null_Object_pattern" target="_blank">
	null object pattern</a> implementation of IEmailSender as <strong>
	NullEmailSender</strong>. You can use it in unit tests or injecting 
	IEmalSender with <a href="Dependency-Injection.html">property injection</a> 
	pattern.</p>
	<h3>Configuration</h3>
	<p>Email Sender uses <a href="Setting-Management.html">setting management</a> 
	system to read emal sending configuration. All setting names are defined in 
	Abp.Net.Mail.EmailSettingNames class as constant strings. Their values and 
	descriptions:</p>
	<ul>
		<li>Abp.Net.Mail.<strong>DefaultFromAddress</strong>: Used as sender 
		email address when you don&#39;t specify a sender while sending emails (as 
		like in the sample above).</li>
		<li>Abp.Net.Mail.<strong>DefaultFromDisplayName</strong>: Used as sender 
		display name when you don&#39;t specify a sender while sending emails (as 
		like in the sample above).</li>
		<li>Abp.Net.Mail.<strong>Smtp.Host</strong>: IP/Domain of the SMTP 
		server (default: 127.0.0.1).</li>
		<li>Abp.Net.Mail.<strong>Smtp.Port</strong>: Port of the SMTP server 
		(default: 25).</li>
		<li>Abp.Net.Mail.<strong>Smtp.UserName</strong>: Username, if SMTP 
		server requires authentication.</li>
		<li>Abp.Net.Mail.<strong>Smtp.Password</strong>: Password, if SMTP 
		server requires authentication.</li>
		<li>Abp.Net.Mail.<strong>Smtp.Domain</strong>: Domain for the username, 
		if SMTP server requires authentication.</li>
		<li>Abp.Net.Mail.<strong>Smtp.EnableSsl</strong>: A value indicates that 
		SMTP server uses SSL or not (&quot;true&quot; or &quot;false&quot;. Default: &quot;false&quot;).</li>
		<li>Abp.Net.Mail.<strong>Smtp.UseDefaultCredentials</strong>: True, to 
		use default credentials instead of provided username and password 
		(&quot;true&quot; or &quot;false&quot;. Default: &quot;true&quot;).</li>
	</ul>
	<h3>MailKit Integration</h3>
	<p>Since .net core does not support standard System.Net.Mail.SmtpClient, so 
	we need a 3rd-party vendor to send emails. Fortunately,
	<a href="https://github.com/jstedfast/MailKit" target="_blank">MailKit</a> 
	provides a good replacement for default SmtpClient. It&#39;s also
	<a href="https://www.infoq.com/news/2017/04/MailKit-MimeKit-Official" target="_blank">
	suggested</a> by Microsoft.</p>
	<p>Abp.MailKit package gracefully integrates to ABP&#39;s email sending system. 
	So, you can still use IEmailSender as described above to send emails via 
	MailKit.</p>
	<h4>Installation</h4>
	<p>First, install
	<a href="https://www.nuget.org/packages/Abp.MailKit" target="_blank">
	Abp.MailKit</a> nuget package to your project:</p>
	<pre>Install-Package Abp.MailKit</pre>
	<h4>Integration</h4>
	<p>Add AbpMailKitModule to dependencies of your <a href="Module-System.html">
	module</a>:</p>
	<pre lang="cs"><strong>[DependsOn(typeof(AbpMailKitModule))]</strong>
public class MyProjectModule : AbpModule
{
    //...
}</pre>
	<h4>Usage</h4>
	<p>You can use <strong>IEmailSender</strong> as described before since 
	Abp.MailKit package <a href="Dependency-Injection.html">registers</a> 
	MailKit implementation for it. It also uses the same configuration defined 
	above.</p>
	<h4>Customization</h4>
	<p>You may need to make additional configuration or customization while 
	creating MailKit&#39;s SmtpClient. In that case, you can
	<a href="Startup-Configuration.html">replace</a> IMailKitSmtpBuilder 
	interface with your own implementation. You can derive from 
	DefaultMailKitSmtpBuilder to make it easier. For instance, you may want to 
	accept all SSL certificates. In that case, you can override ConfigureClient 
	method as shown below:</p>
	<pre lang="cs">public class MyMailKitSmtpBuilder : <strong>DefaultMailKitSmtpBuilder</strong>
{
    public MyMailKitSmtpBuilder(ISmtpEmailSenderConfiguration smtpEmailSenderConfiguration) 
        : base(smtpEmailSenderConfiguration)
    {
    }

    protected override void ConfigureClient(SmtpClient client)
    {
        <strong>client.ServerCertificateValidationCallback = (sender, certificate, chain, errors) =&gt; true;</strong>

        base.ConfigureClient(client);
    }
}</pre>
	<p>Then you can replace IMailKitSmtpBuilder interface with your 
	implementation in <a href="Module-System.html">PreInitialize</a> method of 
	your module:</p>
	<pre lang="cs">[DependsOn(typeof(AbpMailKitModule))]
public class MyProjectModule : AbpModule
{
    public override void PreInitialize()
    {
        <strong>Configuration.ReplaceService&lt;IMailKitSmtpBuilder, MyMailKitSmtpBuilder&gt;();</strong>
    }

    //...
}</pre>
	<p>(remember to add &quot;using Abp.Configuration.Startup;&quot; statement since 
	ReplaceService extension method is defined in that namespace)</p>

</div>

</body>

</html>
